%=======================================================================
% CVS: $Id: ice_refdoc.tex 5 2005-12-12 17:41:05Z mvr $
% CVS: $Source$
% CVS: $Name$
%=======================================================================

\documentclass[]{article}
\usepackage{html}
\usepackage{natbib}
%\usepackage{supertabular}
\setcounter{tocdepth}{7}
\setcounter{secnumdepth}{10}

% create conditional that senses pdf output
\newif\ifpdf
\ifx\pdfoutput\undefined
   \pdffalse
\else
   \pdfoutput=1
   \pdftrue
\fi

% supply correct option to graphicx
\ifpdf
   \usepackage[pdftex]{graphicx}
   \pdfcompresslevel=9
\else
   \usepackage{graphicx}
\fi

\textheight=9.0in
\textwidth=6.5in
\evensidemargin=0.0in
\oddsidemargin=0.0in
\footskip=0.4in   % Positions page number 1 in is too big%
\topmargin=0.0in
\headheight=0.0in
\headsep = 0.0in

\begin{document}
\bodytext{BGCOLOR=white LINK=#083194 VLINK=#21004A}

% This is a modified definition of Ventry from The Latex Companion, p. 64
 \newenvironment{Ventry}[1]%
   {\begin{list}{}{\renewcommand{\makelabel}[1]{\textsf{##1:}\hfil}%
      \settowidth{\labelwidth}{\textsf{#1:}}%
      \setlength{\leftmargin}{1.5cm}%
      \setlength{\labelwidth}{1.0cm}%
      \setlength{\itemsep}{0pt}%
      \setlength{\parsep}{0pt}}}%
   {\end{list}}


% supply correct file suffix to graphicx
\ifpdf
\DeclareGraphicsExtensions{.jpg,.pdf}
\else
\DeclareGraphicsExtensions{.eps,.ps}
\fi

\begin{titlepage}

\vspace*{2in}

\begin{center}
{\Large
  {\bf Community Sea Ice Model (CSIM) Developer's Guide} \\
  {\bf Code Reference for Version 5.0} \\
  \vspace{0.2in}
  {Released with CCSM3.0} \\
  \vspace{.5in}
  Julie Schramm \\
  Cecilia Bitz  \\
  Bruce Briegleb \\
  Marika Holland \\
  Elizabeth Hunke \\
  Bill Lipscomb \\
  Dick Moritz \\
}
\end{center}

\vspace{2in}
\begin{tabular}{p{5in}p{.9in}}
\noindent {\bf Community Climate System Model} \\
\noindent National Center for Atmospheric Research, Boulder, CO \\
\noindent http://www.cgd.ucar.edu/csm/models \\
\hline
\noindent CVS tag \verb+ $Name$  +  Build date: \today \\
\end{tabular}

\end{titlepage}

%===============================================================================

\tableofcontents

\newpage
%===============================================================================


\section {Overview}

This code reference guide accompanies the CSIM5 User's Guide, and is intended
for those whose research requires modifications to the source code rather than 
to the scripts or the namelists.  It is also meant to provide guidance
to users developing code for incorporation into CSIM.  This is only the second
version of this document, so it contains limited information, including a CSIM5
calling tree, some information on the technical aspects of the code, and the
code-interface information generated by the ProTeX utility.  It also includes the
CSIM coding standard and a procedure for integrating software into CSIM.

CSIM is typically run coupled in which case it receives forcing information from
other model components via a flux coupler.  It has been developed to run as the
sea ice component of the NCAR CCSM (Community Climate System Model).  When running uncoupled,
CSIM reads in forcing data from a set of files. Both configurations use the
same source code, so this document can be used with both applications.

The CSIM source code is based on the Los Alamos sea ice model, CICE.
After a code merger with CICE was carried out to take advantage of the vector-
friendly code, the models are very similar.  If there are some topics that
are not covered in the CSIM documentation, users are encouraged to look
at the CICE documentation \cite[]{cice04}.  It is available at
http://climate.lanl.gov/Models/CICE/index.htm.

An attempt has been made throughout this document to provide the following
text convention.  Variable names used in the code are {\tt typewritten}.
Subroutine names are given in {\it italic}, and file names are in {\bf boldface}.
Hereafter, terms shown in {\bf \textsl{slanted boldface}} the first time they
appear in the text are defined in the Glossary. 

%=======================================================================

\subsection {CCSM Directory Structure}
\label{sec:ccsm_dir_structure}

{\bf \textsl{CSIM5}} is located under the {\bf \textsl{CCSM}} models and ice subdirectories.
The directory structure of CSIM5 within CCSM is shown below.  The root directory name of CSIM
remains as {\bf csim4} due to the difficulty of changing it in the source code repository.

\begin{verbatim}
                                ccsm3         (main directory) 
                                  |
                                  |
                 models-----------+------------ scripts
                    |                              |
                    |                              |
      bld--------csm_share-------ice           (build scripts for
       |            |             |             coupled model)
   (Makefile  (share code         |               
    macros)    subdirectory)      | 
                                csim4         (active ice component)
                                  |
                      docs -------+------- src 
                       |                    | 
                     (CSIM                  |
                  documentation)            |
                                            |
                                            |
       bld ------------ input_templates ----+---- source ------ build scripts
       |                    |                       |           for uncoupled
  (Makefile macros     (resolution-dependent    (F90 source     ice model
   for uncoupled         input files)              code) 
    ice model)
\end{verbatim}

Only the branches referenced in this document appear in the Figure. There
are separate directories for the build scripts and the {\bf Macros.*} files for
the coupled model and the uncoupled ice model. The {\bf Macros.*} files
contain machine dependent information for building the model.  The coupled
model uses the {\bf Macros.*} files in {\bf ccsm3/models/bld}, and the
uncoupled ice model uses those in {\bf ccsm3/models/ice/csim4/src/bld}.
To make modifications to the coupled model setup, modify the scripts in 
{\bf ccsm3/scripts}.  The setup scripts for the uncoupled model are
located in {\bf ccsm3/models/ice/csim4/src}.  The files located under
the main ice model directory {\bf /csim4/src} are described in the next section.

%\subsection {CSIM Directory Structure}
\input{ice_module_desc}

%\subsection {External Software and Libraries}
\input{ice_softw_libs}


%=======================================================================
\section {Model Structure}

CSIM5 is written in the Fortran 90 programming language in fixed source
form.   It is parallelized internally by grid decomposition using
{\bf \textsl{MPI}} (Message Passing Interface).  There is an external layer of
parallelization, also using MPI, that allows message passing between the ice
model and the coupler.

\input {ice_dt_loop}

%\subsection {Information Exchanged with the Coupler}
\input{ice_cpl_exch}

%\subsection {Global Grid and Grid Decomposition} 
\input {ice_grid} 

%\section {Making Code Modifications} 
\input{ice_making_mods}

%\section{Code Management under CVS}
\input{ice_code_cvs}

%\section{Coding Standard}
\input{ice_code_std}

%\section{Integration}
\input{ice_integrate}

%\input{notes_for_guide}

%\section{Glossary}
\input{ice_glos}

\bibliographystyle{../UsersGuide/jas}
\bibliography{../UsersGuide/master_list}
\addcontentsline{toc}{section}{References}

\appendix 
\section {Calling Tree}
\label{calling_tree}

This section contains the primary calling tree for the coupled ice model. Calls
to MPI, netCDF, share code routines, subroutines or functions within the ice model
that do not include ice physics (i.e. global\_scatter, get\_sum, bound, etc.) are
not included.  Calls to the slab ocean mixed layer model within the ice model are
shown in square brackets.

\input{ice_calltree.tex}

\section {ProTeX Generated Documentation}

This appendix contains the module and subroutine documentation generated by ProTeX.
This section is available at \\
http://www.ccsm.ucar.edu/models/ccsm3/csim/RefGuide/ice\_refdoc/index.html .

%\input ice_protex.tex  % 

\end{document}


